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ABSTRACT 

AUTOADJ  is  a  computer  program  for  creating  adja- 
cency and  mutually  exclusive  constraints  for  polygons  in 
the  Integrated  Resource  Analysis  System  (IRAS)  and  the 
Integrated  Resource  Planning  Model  (IRPM).  It  is  interac- 
tive and  operates  on  the  Forest  Service's  Data  General 
system. 
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Adjacency  constraints  prevent  undesirable  combina- 
tions of  management  projects  from  being  scheduled  on 
adjacent  polygons  in  Integrated  Resource  Analysis  Sys- 
tem (IRAS)  models  (Jones  and  others  1989)  and  in  Inte- 
grated Resource  Planning  Models  (IRPM)  (Kirby  and 
others  1980).  A  common  application  of  adjacency  con- 
straints is  to  prevent  selecting  adjacent  polygons  for  har- 
vest within  the  same  time  period  or  within  two  or  more 
consecutive  time  periods. 

Preparing  the  data  for  these  constraints  manually  is 
very  time  consuming  and  tedious.  Moreover,  it  is  easy  to 
inadvertently  omit  one  or  more  common  boundaries.  The 
result  is  an  invalid  model  that  can  be  corrected  only  by 
adding  the  missing  boundary  specifications  to  the  data 
and  regenerating  the  model. 

AUTOADJ  is  a  computer  program  automating  data 
entry  for  adjacency  constraints  in  IRAS  and  IRPM 
models.  In  addition,  AUTOADJ  creates  another  type  of 
constraint  commonly  used  in  these  models — a  mutually 
exclusive  constraint  for  each  polygon.  These  constraints 
allow  the  selection  of  only  one  management  option  per 
polygon. 

AUTOADJ  operates  on  the  Forest  Service  Data  General 
(DG)  system.  It  is  interactive,  but  relies  on  two  files  for 
input.  One  is  an  input  file  for  the  IRPM  matrix  generator 
(also  used  in  IRAS).  The  second  is  a  file  listing  neighbor- 
ing polygons.  This  note  describes  the  operation  of 
AUTOADJ. 


'J.  Greg  Jones  is  a  Research  Forester  and  Mary  L.  Meacham  is  a  Statis- 
tician. Both  are  located  at  the  Intermountain  Station's  Forestry  Sciences 
Laboratory,  Missoula,  MT. 


OVERVIEW 

The  information  for  building  adjacency  constraints  with 
AUTOADJ  is  entered  interactively.  But  data  for  the  adja- 
cency constraints  and  the  mutually  exclusive  constraints 
for  polygons  come  from  two  previously  built  files.  Both 
must  be  located  on  your  DG  system.  One  is  the  input  file 
for  the  IRPM  matrix  generator  called  DATA.PRELIM. 
This  file  contains  data  for  the  resource  projects,  which 
are  the  land  management  options  for  the  polygons. 
AUTOADJ  uses  this  file  to  develop  a  comprehensive  list 
of  resource  projects.  Readers  are  referred  to  the  IRPM 
manual  (Kirby  and  others  1980)  for  the  format  of 
DATA.PRELIM. 

The  other  file,  called  the  polygon  neighbor  file,  contains 
a  list  of  adjacent  polygons.  This  information  is  entered  in 
file  form  to  provide  flexibility.  It  may,  for  example,  be 
built  electronically  using  digital  map  data,  or  built  manu- 
ally using  a  text  editor.  (The  format  for  this  file  is  pre- 
sented later.) 

AUTOADJ  requires  that  the  resource  projects  in 
DATA.PRELIM  be  coded  with  the  convention  adopted  for 
IRAS: 

Resource  Project  Coding  =  XXXXIT 
where: 

XXXX    =    A  numerical  code  representing  the  polygon 
to  which  the  resource  project  applies.  All 
four  digits  must  be  used.  (For  example 
polygon  1  would  be  coded  0001.) 

I  =  An  increment  code  (number  0-9  or  a  letter 
A-Z)  used  to  differentiate  among  resource 
projects  implementable  in  a  common  time 
period  on  the  same  polygon. 

T     =    The  time  period  (number  1-5)  associated 

with  a  resource  project.  This  period  is  used 
by  AUTOADJ  in  formulating  the  adjacency 
constraints.  For  example,  resource  projects 
having  a  value  of  2  for  T  would  be  included 
in  the  period  2  adjacency  constraints. 

AUTOADJ  provides  the  option  of  excluding  resource 
projects  having  specified  increment  codes  (I)  from  the 
adjacent  constraints.  This  might  apply,  for  example,  to 
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resource  projects  representing  selective  harvesting,  which 
is  permitted  on  adjacent  polygons.  To  accomplish  this,  all 
selective  harvesting  projects  in  DATA.PRELIM  would  be 
assigned  the  same  increment  code,  say  the  number  9. 
Then,  specify  in  AUTOADJ  that  resource  projects  having 
this  increment  code  are  to  be  excluded  from  the  adjacency 
constraints. 

AUTOADJ  uses  the  approach  described  in  Meneghin 
and  others  (1988)  to  build  what  are  called  "type  1"  adja- 
cency constraints.  In  these  constraints  the  sum  of  a  group 
adjacent  resource  projects  is  constrained  to  be  less  than  or 
equal  to  one.  For  example,  a  "type  1"  adjacency  constraint 
including  projects  X1  through  XA  would  be  formulated  as: 

x1  +x2  +  x3  +  xi  £l. 

Because  the  value  of  1  for  a  resource  project  means  that 
the  resource  project  should  be  implemented  in  its  en- 
tirety, the  solution  process  may  select  at  most  the  equiva- 
lent of  one  whole  project  from  this  group  of  adjacent 
projects. 

The  mutually  exclusive  constraints,  which  allow  the 
selection  of  only  one  resource  project  per  polygon,  are 
formulated  in  the  same  manner.  The  sum  of  all  resource 
projects  applying  to  a  specific  polygon  is  constrained  to  be 
less  than  or  equal  to  1. 

The  output  from  AUTOADJ  is  written  to  a  user- 
specified  file,  and  is  in  the  format  required  by  the  IRPM 
matrix  generation  process.  This  file  should  be  placed  in 
the  NCC-FC  file  called  DATA.USER-MCARDS  along  with 
the  specifications  for  other  types  of  constraints  to  be  in- 
cluded in  the  IRAS  or  IRPM  model. 

ACQUIRING  AND  RUNNING 
AUTOADJ 

Two  files  are  needed  to  run  AUTOADJ,  the  executable 
FORTRAN  program  (AUTOADJ.PR)  and  a  sort  procedure 
(AUTOADJ_SORT).  Copies  of  these  files  can  be  obtained 
from  the  Intermountain  Research  Station  using  the  DG 
file  retrieval  procedure.  The  information  for  retrieving 
these  files  is  as  follows: 

Host  Name:  S22L01A 
Level:  2  (staff) 
Staff  Name:  ECON 
Drawer  Name:  PROGRAMS 
Folder  Name:  PROGRAMS 
File  Name:  AUTOADJ.PR 

AUTOADJ_SORT 

The  retrieved  files  should  be  stored  in  IS/CLI  and  given 
the  same  names. 

To  execute  AUTOADJ,  type  <X  AUTOADJ'  on  the  IS/ 
CLI  command  line.  First  the  banner  page  appears  on  the 
screen.  It  is  important  to  note:  (1)  the  functions  available 
(INDEX  =  Shift-F2,  and  BACKFIELD  =  Shift-Fll)  and  (2) 
this  program  can  be  terminated  at  most  locations  by  typ- 
ing 'stop'.  Press  <NEWLINE>  to  continue. 


Next,  the  two  main  program  options  are  listed.  Select 
'1'  if  AUTOADJ  is  to  build  ONLY  the  mutually  exclusive 
constraints  for  the  polygons  in  a  model.  Select  '2'  if 
AUTOADJ  is  to  build  BOTH  the  mutually  exclusive  con- 
straints for  the  polygons  and  the  adjacency  constraints. 

After  the  option  is  selected,  the  user  is  asked  for  the 
names  of  the  two  input  files  and  the  output  file.  If  pro- 
gram option  '2'  is  selected,  the  name  of  the  polygon  neigh- 
bor file  is  requested  first.  (See  "Polygon  Neighbor  File" 
for  the  format  requirements.)  AUTOADJ  checks  the  first 
line  of  the  file  specified  to  ensure  that  it  contains  the 
letters  'ADJ'  in  columns  1-3.  If  not,  the  file  name  pro- 
vided is  rejected  and  the  user  is  asked  to  supply  the  name 
of  a  valid  polygon  neighbor  file.  (Note:  the  program  can 
be  terminated  at  this  point  by  typing  'stop'.) 

The  next  file  name  is  requested  for  both  options.  This 
file  contains  the  input  data  for  the  IRPM  data  file  called 
DATA.PRELIM.  AUTOADJ  checks  this  file  for  format.  If 
the  format  is  inconsistent  with  DATA.PRELIM,  the  user 
is  asked  to  enter  another  file  name.  (Readers  are  referred 
to  the  IRPM  manual  (Kirby  and  others  1980)  for  the  for- 
mat of  DATAPRELIM.) 

The  final  name  requested  is  for  the  output  file. 
AUTOADJ  writes  the  data  for  both  the  mutually  exclusive 
constraints  for  the  polygons  and  the  adjacency  constraints 
to  the  file  specified.  If  data  errors  are  found,  however, 
error  statements  are  written  to  this  file  instead. 

If  program  option  1  was  selected  (create  only  mutually 
exclusive  constraints  for  the  polygons),  AUTOADJ  begins 
processing  data  upon  entry  of  the  file  names.  If  option  2 
was  selected,  AUTOADJ  asks  if  any  increment  codes 
should  be  omitted  from  adjacency  constraints.  If  an- 
swered    the  user  is  asked  to  supply  the  increment  codes 
for  resource  projects  to  be  omitted.  Up  to  36  increment 
codes  can  be  entered.  (See  coding  for  resource  projects 
under  Overview  for  a  description  of  increment  code.)  All 
resource  projects  having  the  specified  increment  code(s) 
will  be  omitted  from  the  adjacency  constraints. 

Next,  AUTOADJ  requests  the  periods  over  which  the 
adjacency  restrictions  apply.  A  separate  "set"  of  adja- 
cency constraints  should  be  created  for  each  period  or 
sequence  of  periods,  within  which  adjacent  units  are  not 
to  be  harvested.  Press  <NEWLINE>  on  an  empty  field  to 
continue  the  program  after  all  adjacency  sets  have  been 
specified.  Specifying  adjacency  sets  is  illustrated  below 
with  two  examples,  each  containing  three  time  periods. 

Example  1:  Adjacent  polygons  are  not  to  be  harvested 
within  two  consecutive  periods.  (Two  adja- 
cency sets  are  required:  one  to  specify  that 
adjacent  polygons  cannot  be  harvested  in 
periods  1  and  2,  the  other  to  specify  that 
adjacent  polygons  cannot  be  harvested  in 
periods  2  and  3.) 

Adj.  constr. 

set  Period(s) 

A  1,2 

B  2,3 

C  <NEWLINE> 
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Example  2:  Adjacent  polygons  are  not  to  be  harvested 

within  periods  1  or  2,  or  within  period  three. 
Adjacent  polygons  may  be  harvested  in  peri- 
ods 1  and  3,  or  2  and  3.  (Two  adjacency  sets 
are  required:  one  to  specify  that  adjacent 
polygons  cannot  be  harvested  in  periods  1 
and  2,  the  other  to  specify  that  adjacent  poly- 
gons cannot  be  harvested  in  period  3.) 


Adj.  constr. 
set 

A 
B 

C 


Period(s) 

1,2 

3 

<NEWLINE> 


After  <NEWLINE>  is  pressed  without  entering  another 
time  period,  AUTOADJ  computes  the  data  for  the  mutu- 
ally exclusive  constraints  and  the  adjacency  constraints 
and  writes  it  to  the  specified  output  file.  If,  however, 
inconsistencies  or  errors  are  found,  error  statements  are 
written  to  the  output  file  instead. 

The  constraint  data  created  by  AUTOADJ  must  be 
placed  in  the  NCC-FC  file  DATA.USER-MCARDS  prior  to 
running  the  matrix  generation  procedures.  The  final 
question  asked  is  whether  the  user  would  like  AUTOADJ 
to  append  the  output  file  just  created  to  the  DG  file  con- 
taining records  for  DATA.USER-MCARDS.  If  answered 
TT  the  user  is  asked  for  the  name  of  the  file  to  be  ap- 
pended. AUTOADJ  stops  upon  completion  of  this  step. 

POLYGON  NEIGHBOR  FILE 

The  polygon  neighbor  file  is  needed  only  when  adja- 
cency constraints  are  to  be  created.   It  contains  a  list  of 
all  adjacent  polygons.  Polygon  ID's  must  be  four  numeric 
characters  (for  example  polygon  1  must  be  entered  as 
0001)  and  must  be  the  same  polygon  ID's  used  for  the 
resource  projects  (NCC-FC  file  DATA.PRELIM).  Up  to 
900  polygons  can  be  accommodated.  The  format  for  this 
file  follows: 


Line(s)  Column 
1  1-3 


2+ 


2+ 


2-5 


10-78 


Entry 

ADJ  (used  an  identifier) 

The  pointer  polygon  ID.  Each 
polygon  having  neighbors  must 
appear  in  this  location  once  (one 
record  for  each  polygon). 

The  polygons  that  are  adjacent 
to  the  pointer  polygon  are 
listed,  beginning  in  column  10. 
The  four-character  polygon  ID's 
should  be  separated  by  either  a 
blank  or  a  comma.  Include  all 
adjacent  polygons  even  though 
they  may  have  already  been 
listed  on  other  records.  Up  to 
14  adjacent  polygons  may  be 
listed  for  each  pointer  polygon. 


ERROR  STATEMENTS 

AUTOADJ  checks  for  the  presence  of  specified  input 
files.  If  a  specified  file  is  not  found,  the  user  is  notified 
and  asked  to  provide  another  file  name.  AUTOADJ  also 
checks  the  input  files  for  key  identifying  features.  If  a 
specified  file  does  not  contain  these  key  features,  the  user 
is  notified  and  asked  to  provide  the  name  of  another  file. 

AUTOADJ  also  checks  for  two  types  of  data  inconsis- 
tencies. First,  it  checks  the  periods  specified  for  the  adja- 
cency constraint  sets  against  the  periods  associated  with 
the  resource  projects  (found  in  the  data  for  the  NCC-FC 
file  DATA.PRELIM).  There  must  be  at  least  some  re- 
source projects  associated  with  the  periods  specified  for 
the  adjacency  constraint  sets.  If  not,  the  user  is  notified 
that  a  particular  period  was  not  found  in  the  land  man- 
agement project  data,  and  is  asked  to  revise  the  periods 
specified  for  the  adjacency  constraint  sets. 

The  second  data  check  performed  by  AUTOADJ  com- 
pares the  polygons  in  the  polygon  neighbor  file  with  the 
data  for  file  DATA.PRELIM.  If  no  resource  projects  are 
found  for  a  polygon  listed  in  the  polygon  neighbor  file  the 
following  error  is  written  both  to  the  screen  and  to  the 
output  file: 

***  No  Resource  Projects  were  found  in  


for  polygon  listed  in  the  polygon  neighbor  file. 

Likely  causes  are  (a)  a  polygon  was  mistakenly  included 
in  the  polygon  neighbor  file  and  should  be  removed  from 
that  file;  or  (b)  data  were  omitted  for  the  specified  polygon 
in  DATA.PRELIM.  Whatever  the  cause,  this  data  incon- 
sistency must  be  eliminated  before  AUTOADJ  will  write 
the  mutually  exclusive  and  adjacency  constraints  in  the 
output  file. 
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The  Intermountain  Research  Station  provides  scientific  knowledge  and  technology  to  im- 
prove management,  protection,  and  use  of  the  forests  and  rangelands  of  the  Intermountain 
West.  Research  is  designed  to  meet  the  needs  of  National  Forest  managers,  Federal  and 
State  agencies,  industry,  academic  institutions,  public  and  private  organizations,  and  individu- 
als. Results  of  research  are  made  available  through  publications,  symposia,  workshops, 
training  sessions,  and  personal  contacts. 

The  Intermountain  Research  Station  territory  includes  Montana,  Idaho,  Utah,  Nevada,  and 
western  Wyoming.  Eighty-five  percent  of  the  lands  in  the  Station  area,  about  231  million 
acres,  are  classified  as  forest  or  rangeland.  They  include  grasslands,  deserts,  shrublands, 
alpine  areas,  and  forests.  They  provide  fiber  for  forest  industries,  minerals  and  fossil  fuels  for 
energy  and  industrial  development,  water  for  domestic  and  industrial  consumption,  forage  for 
livestock  and  wildlife,  and  recreation  opportunities  for  millions  of  visitors. 

Several  Station  units  conduct  research  in  additional  western  States,  or  have  missions  that 
are  national  or  international  in  scope. 

Station  laboratories  are  located  in: 

Boise,  Idaho 

Bozeman,  Montana  (in  cooperation  with  Montana  State  University) 
Logan,  Utah  (in  cooperation  with  Utah  State  University) 
Missoula,  Montana  (in  cooperation  with  the  University  of  Montana) 
Moscow,  Idaho  (in  cooperation  with  the  University  of  Idaho) 
Ogden,  Utah 

Provo,  Utah  (in  cooperation  with  Brigham  Young  University) 
Reno,  Nevada  (in  cooperation  with  the  University  of  Nevada) 

USDA  policy  prohibits  discrimination  because  of  race,  color,  national  origin,  sex,  age,  reli- 
gion, or  handicapping  condition.  Any  person  who  believes  he  or  she  has  been  discriminated 
against  in  any  USDA-related  activity  should  immediately  contact  the  Secretary  of  Agriculture, 
Washington,  DC  20250. 


The  use  of  trade  or  firm  names  in  this  publication  is  for  reader  infor- 
mation and  does  not  imply  endorsement  by  the  U.S.  Department  of 
Agriculture  of  any  product  or  service. 


Intermountain  Research  Station 
324  25th  Street 
Ogden,  UT  84401 


